<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
	<TITLE>Readme for event example</TITLE>
	<META NAME="GENERATOR" CONTENT="OpenOffice.org 2.0  (Linux)">
	<META NAME="CREATED" CONTENT="20060627;17353000">
	<META NAME="CHANGEDBY" CONTENT="kejin">
	<META NAME="CHANGED" CONTENT="20070608;1454000">
	<STYLE TYPE="text/css">
	<!--
		@page { size: 8.5in 11in }
		P { color: #000000 }
		H2 { color: #000000 }
		H3 { color: #000000 }
		PRE { color: #000000 }
		A:link { color: #0000ff }
		A:visited { color: #990066 }
	-->
	</STYLE>
</HEAD>
<BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" VLINK="#990066" BGCOLOR="#ffffff" DIR="LTR">
<H2>PocoCapsule/C++ CORBA example: OMG Event/Notification 
</H2>
<P>Copyright(c) 2006, 2007 by <A HREF="http://www.pocomatic.com/">Pocomatic
Software</A>. All rights reserved.</P>
<P>This example is similar to the event example in the
<A HREF="../event/README.html">examples/corba/event</A> directory
except for the event listeners in this example are implemented as
separated POA servants inherited from their respective event
interface POA skeletons. 
</P>
<P>This example illustrates how to assemble and deploy event supplier
and event consumer applications and use OMG Notification service to
build a distributed publish/subscribe system. Following POEM (namely
Plain Old Event Model) scenarios are covered by this example:</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in">typed event : <FONT SIZE=2>The
	event operation signatures are defined by users in IDL interfaces.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in">structured event : <FONT SIZE=2>The
	event operation and format are predefined by OMG notification
	service.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in">sequence event : <FONT SIZE=2>The
	event is a sequence of structured events.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in">untyped event : <FONT SIZE=2>The
	event is a CORBA::Any encapsulates arbitrary IDL types defined by
	users.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in">type event with filter : <FONT SIZE=2>similar
	to typed event. The event subscriber (consumer) set a filter to
	eliminate certain unwanted events.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in">structured event with filter :
	<FONT SIZE=2>similar to structured event. The event subscriber
	(consumer) set a filter to eliminate certain unwanted events.</FONT></P>
</UL>
<P>Traditional programmatic approach would require significant amount
of boilerplate code in developing above event supplier or consumer
applications. Certain scenarios above, for instance the filters and
typed event, were even challenges to most CORBA professionals. With
PocoCapsule/CORBA application deployment, all above scenarios become
straightforward even for novice. Most complexities and boilerplate
code are moved into PocoCapsule/CORBA. Developers should only need to
know and focus on implementing event emitting and receiving objects
(beans), and no longer need to care how to connect them to the OMG
notification service. The development procedure of a POCO+POEM
application is roughly as follows:</P>
<OL>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>Implement emitters
	and listeners as POCO beans, which emit and receive POEM events.
	During this phase, developers only need to focus on defining their
	application events formats (namely, type, topic, etc.), and
	implementing application/business logic of event generating and
	consuming. </FONT>
	</P>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>Declare type (namely,
	&quot;typed&quot;, &quot;structured&quot;, &quot;sequence&quot; and
	&quot;untyped&quot;) and topic (only applies to &quot;structured&quot;
	and &quot;typed&quot; events) of events that are going to be
	published/subscribed by each emitter/listener, and the location of
	event service (or channel, admin) in XML descriptors. At this stage,
	developers only need to conceptually declare “<B><I>what</I></B>”
	publish/subscribe connections they want, instead of imperatively
	specify “<B><I>how</I></B>” the container should establish these
	connections.</FONT></P>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>Deploy the
	application in PocoCapsule. which will activate emitter/listener
	beans and connect them to OMG notification service based on “<B><I>what</I></B>”
	is described. </FONT>
	</P>
</OL>
<P>As POCO beans are plain old C++ objects, and POEM events are any
ordinary OMG Notification service events defined in conventional
applications. An application developed in above scenario has no
dependency on the PocoCapsule container itself, and therefore, their
application/business logic (namely event generating and consumption)
can be unit tested/used outside the container.</P>
<H3>Source Files</H3>
<P><A HREF="MyTypedEvent.idl">MyTypedEvent.idl:</A> This is the IDL
definition of a typed event interface<B>.</B> 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>Three event sending
	operations are defined on this typed event interface, namely
	hello(), headlinenews() and stockquote().</FONT></P>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>The
	client stub and server skeleton classes source code from this IDL
	can be generated using the given ORB's IDL-to-C++ pre-compiler, for
	instance, the idl2cpp of VisiBroker/C++.. </FONT></FONT>
	</P>
</UL>
<P><A HREF="publisher.C">publisher.C:</A> This is a simple container,
used to deploy event emitter beans. 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>This
	publisher example assumes the OMG Notification service's IOR or URL
	is specified as in the main command line arguments to be passed to
	the ORB_init() (see “<I>Running this example”</I> section)</FONT></FONT></P>
</UL>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><FONT SIZE=2>-ORBInitRef NotificationService=&lt;ior or url of the service&gt;</FONT></FONT></PRE>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>This
	example also assumes the event type selector -- <I>typed, untyped,
	structured </I>or <I>sequence</I>, is passed in as first
	command-line argument. (also see “<I>Running this example”</I>
	section) </FONT></FONT>
	</P>
</UL>
<P><A HREF="subscriber.C">subscriber.C:</A> This is a simple
container, used to deploy event listener beans. 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>This
	subscriber example assumes the OMG Notification service's IOR or URL
	is specified in the main command line arguments to be passed to the
	ORB_init() (see “<I>Running this example”</I> section)</FONT></FONT></P>
</UL>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><FONT SIZE=2>-ORBInitRef NotificationService=&lt;ior or url of the service&gt;</FONT></FONT></PRE>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>This
	example also assumes the event type selector -- <I>typed, untyped,
	structured </I>or <I>sequence</I>, is passed in as first
	command-line argument. (also see “<I>Running this example”</I>
	section) </FONT></FONT>
	</P>
</UL>
<P><A HREF="EmitterImpl.h">EmitterImpl.h</A> and <A HREF="EmitterImpl.C">EmitterImpl.C:</A>
They provide the implementation of an event emitter class, the
EventEmitterImpl. It supports OMG standardized operations to inject
typed, structured, sequence and untyped <I>proxy consumer</I>
references.</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>void
	connect_typed_push_consumer(CosTypedEventComm::TypedPushConsumer_ptr
	consumer);</FONT></P>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>void
	connect_structured_push_consumer(CosNotifyComm::StructuredPushConsumer_ptr
	consumer);</FONT></P>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>void
	connect_sequence_push_consumer(CosNotifyComm::SequencePushConsumer_ptr
	consumer);</FONT></P>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2>void
	connect_any_push_consumer(CosEventComm::PushConsumer_ptr consumer);</FONT></P>
</UL>
<P><A HREF="ListenerImpl.h">ListenerImpl.h</A> and <A HREF="ListenerImpl.C">ListenerImpl.C</A>:
They provide servant implementations of event listener classes, the
<I>Typed/Structured/Sequence/Untype EventListenerImpl</I>. 
</P>
<P><A HREF="publish.xml">publish.xml:</A> This is the deployment
descriptor of the event publisher application. 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in">It declares 4 event supplier
	adapters of <I>typed, structured, sequence</I> and <I>untyped</I>
	respectively. These adapters are declared to be “lazy-init”,
	therefore, in this case, will only be instantiated when getBean() is
	called with their id from the main() of publisher.C. This publisher
	chooses an event supplier adapter to initiate based on user input
	args[0].</P>
</UL>
<P><FONT SIZE=2><A HREF="subscribe.xml"><FONT SIZE=3>subscribe.xml:</FONT></A>
<FONT SIZE=3>This is the deployment descriptor of the event
subscriber application. </FONT></FONT>
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=3>It declares 6 event
	consumer adapters of t<I>yped, structured, sequence, untyped, typed
	with filter </I>and <I>structured with filter</I> respectively.
	These adapters are declared to be “lazy-init”, therefore, in
	this case, will only be instantiated when getBean() is called with
	their id from the main() of subscriber.C. The subscriber chooses a
	listener to initiate based on user input args[0].</FONT></P>
</UL>
<H3>Building this example</H3>
<P STYLE="font-weight: medium">To build this example, the environment
variable POCOCAPSULE_DIR should point to the PocoCapsule/C++
installed directory. Also, this example assumes an underneath ORB
(e.g. VisiBroker/C++, TAO, etc.) is installed and its runtime and
development environment (such as POCOCAPSULE_DIR, VBROKER_DIR or
TAO_ROOT, etc. env variable) are set according to its product
specification. Then, this example can be built by simply invoking
gmake/make on linux/unix or nmake on windows. 
</P>
<H3>Running this example</H3>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Before
starting the server</FONT></B><FONT FACE="Times New Roman">, make
sure the LD_LIBRARY_PATH (on linux and solaris) or the PATH (on
windows) environment variable is set correctly to include the
${POCOCAPSULE_DIR}/lib directory and the ${VBROKREDIR}/lib (if
VisiBroker is used) or the ${TAO_ROOT}/lib directory (if TAO is
used).</FONT></P>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Start
a OMG Notification service</FONT></B> <FONT FACE="Times New Roman">(or
typed service, if separate), for instance, VisiNotify, TAO or
JacORB's notification service. VisiNotify supports typed as well as
predefined (structured/sequence/untyped) event services in one
server. The default service URL is:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch">corbaloc::&lt;host&gt;:14100/NotificationService</FONT></PRE><P>
<FONT FACE="Times New Roman">Here, &lt;host&gt; is the domain or
dotted IP address of the Notification service server. </FONT>
</P>
<P><FONT FACE="Times New Roman">JacORB notification service supports
typed and predefined event services in two separate servers,
therefore, if they are on same host at same time, they must be
started on different ports. The server port by default is chosen
automatically from dynamic port range. User can also specify a
desired port number with -port &lt;port&gt; command line option. On
successful startup, JacORB notification server print out the service
URL, for instance:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch">corbaloc::&lt;host&gt;:&lt;port&gt;/NotificationService </FONT></PRE><P>
<FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman"><B>Start
the subscriber(s) as</B>:</FONT></P>
<PRE STYLE="margin-left: 0.79in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  subscriber (typed|structured|sequence|untyped|typed-filter|structured-filter) \</FONT>
         <FONT FACE="Courier 10 Pitch">-ORBInitRef NotificationService=&lt;service URL&gt;</FONT></PRE><P>
<FONT FACE="Times New Roman">For instance, to start a structured
event subscriber and connect it to a Notification service on address
192.168.2.2 port 14100, the command line should look like:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  subscriber structured -ORBInitRef NotificationService=corbaloc::192.168.2.2:14100/NotificationService</FONT></PRE><P>
<FONT FACE="Times New Roman">Here, the -ORBInitRef option and the
format of the corbaloc URL are all specified in OMG CORBA and
Notification Service standard. Multiple subscribers can be started in
order to observer event multi-casting. </FONT>
</P>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Start
the publisher as<FONT FACE="Times New Roman">:</FONT></FONT></B></P>
<PRE STYLE="margin-left: 0.79in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  publisher (typed|structured|sequence|untyped) \</FONT>
         <FONT FACE="Courier 10 Pitch">-ORBInitRef NotificationService=&lt;service URL&gt;</FONT></PRE><P>
<FONT FACE="Times New Roman">For instance, to start a typed event
supplier and connect it to a Notification service on address
192.168.2.2 port 14100, the command line should look like:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  subscriber typed -ORBInitRef NotificationService=corbaloc::192.168.2.2:14100/NotificationService</FONT></PRE><P STYLE="font-weight: medium">
<FONT FACE="Times New Roman">Here, the -ORBInitRef option and the
format of the corbaloc URL are all specified in OMG CORBA and
Notification Service standard. </FONT>
</P>
<P STYLE="font-weight: medium">On successful connection, typed
emitter will push 3 typed events. On receiving these 3 events, a
typed event subscriber will print out the following messages:</P>
<PRE STYLE="margin-left: 0.79in"><FONT FACE="Courier 10 Pitch"><FONT SIZE=2>...</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>received a hello 'Greeting to everyone' event from info service</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>received a headline news: {'new POCO release', 'POCO is a Plain Old Common Object container'} event from info service</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>received a stockquote: id=POCO, quote=120.000000 event</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>...</FONT></FONT></PRE><P STYLE="font-weight: medium">
other emitters each will push 20 events to the notification channel.
A subscriber will also print out the messages on receiving them. For
instance, for each individual received structured event, a structured
event subscriber will print a message similar to the following one:</P>
<PRE STYLE="margin-left: 0.79in"><FONT FACE="Courier 10 Pitch"><FONT SIZE=2>...</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>---- received a structured event ----</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>event.header {</FONT></FONT>
  <FONT FACE="Courier 10 Pitch">.fixed_header {</FONT>
    <FONT FACE="Courier 10 Pitch">.event_type {</FONT>
      <FONT FACE="Courier 10 Pitch">.domain_name = 'pocomatic'</FONT>
      <FONT FACE="Courier 10 Pitch">.type_name = 'com'</FONT>
    <FONT FACE="Courier 10 Pitch">}</FONT>
    <FONT FACE="Courier 10 Pitch">.event_name = 'stockquote'</FONT>
  <FONT FACE="Courier 10 Pitch">}</FONT>
  <FONT FACE="Courier 10 Pitch">.variable_header {</FONT>
    <FONT FACE="Courier 10 Pitch">[0] { .name='time', .value='12:12:59' }</FONT>
  <FONT FACE="Courier 10 Pitch">}</FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>}</FONT></FONT>
  <FONT FACE="Courier 10 Pitch">.filterable_data {</FONT>
    <FONT FACE="Courier 10 Pitch">[0] { .name='hello', .value='from provider' }</FONT>
  <FONT FACE="Courier 10 Pitch">}</FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>}</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>.reminder_of_body = 'structured event count 20'</FONT></FONT>
<FONT FACE="Courier 10 Pitch"><FONT SIZE=2>...</FONT></FONT></PRE><P STYLE="font-weight: medium">
By default, POCO will set the destroy method to disconnect the proxy
consumer created in the notification service. This method is called,
when the <I>terminate</I>() method is called on the poco application
context (see publisher.C). 
</P>
<P><A HREF="../../README.html">Back to the root page</A></P>
</BODY>
</HTML>